<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Chapter 46. Zend_Validate</title>
<link rel="stylesheet" href="dbstyle.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.72.0">
<link rel="start" href="index.html" title="Programmer's Reference Guide">
<link rel="up" href="index.html" title="Programmer's Reference Guide">
<link rel="prev" href="zend.uri.html" title="Chapter 45. Zend_Uri">
<link rel="next" href="zend.validate.set.html" title="46.2. Standard Validation Classes">
<link rel="chapter" href="introduction.html" title="Chapter 1. Introduction to Zend Framework">
<link rel="chapter" href="zend.acl.html" title="Chapter 2. Zend_Acl">
<link rel="chapter" href="zend.auth.html" title="Chapter 3. Zend_Auth">
<link rel="chapter" href="zend.cache.html" title="Chapter 4. Zend_Cache">
<link rel="chapter" href="zend.config.html" title="Chapter 5. Zend_Config">
<link rel="chapter" href="zend.console.getopt.html" title="Chapter 6. Zend_Console_Getopt">
<link rel="chapter" href="zend.controller.html" title="Chapter 7. Zend_Controller">
<link rel="chapter" href="zend.currency.html" title="Chapter 8. Zend_Currency">
<link rel="chapter" href="zend.date.html" title="Chapter 9. Zend_Date">
<link rel="chapter" href="zend.db.html" title="Chapter 10. Zend_Db">
<link rel="chapter" href="zend.debug.html" title="Chapter 11. Zend_Debug">
<link rel="chapter" href="zend.dojo.html" title="Chapter 12. Zend_Dojo">
<link rel="chapter" href="zend.dom.html" title="Chapter 13. Zend_Dom">
<link rel="chapter" href="zend.exception.html" title="Chapter 14. Zend_Exception">
<link rel="chapter" href="zend.feed.html" title="Chapter 15. Zend_Feed">
<link rel="chapter" href="zend.filter.html" title="Chapter 16. Zend_Filter">
<link rel="chapter" href="zend.form.html" title="Chapter 17. Zend_Form">
<link rel="chapter" href="zend.gdata.html" title="Chapter 18. Zend_Gdata">
<link rel="chapter" href="zend.http.html" title="Chapter 19. Zend_Http">
<link rel="chapter" href="zend.infocard.html" title="Chapter 20. Zend_InfoCard">
<link rel="chapter" href="zend.json.html" title="Chapter 21. Zend_Json">
<link rel="chapter" href="zend.layout.html" title="Chapter 22. Zend_Layout">
<link rel="chapter" href="zend.ldap.html" title="Chapter 23. Zend_Ldap">
<link rel="chapter" href="zend.loader.html" title="Chapter 24. Zend_Loader">
<link rel="chapter" href="zend.locale.html" title="Chapter 25. Zend_Locale">
<link rel="chapter" href="zend.log.html" title="Chapter 26. Zend_Log">
<link rel="chapter" href="zend.mail.html" title="Chapter 27. Zend_Mail">
<link rel="chapter" href="zend.measure.html" title="Chapter 28. Zend_Measure">
<link rel="chapter" href="zend.memory.html" title="Chapter 29. Zend_Memory">
<link rel="chapter" href="zend.mime.html" title="Chapter 30. Zend_Mime">
<link rel="chapter" href="zend.openid.html" title="Chapter 31. Zend_OpenId">
<link rel="chapter" href="zend.paginator.html" title="Chapter 32. Zend_Paginator">
<link rel="chapter" href="zend.pdf.html" title="Chapter 33. Zend_Pdf">
<link rel="chapter" href="zend.registry.html" title="Chapter 34. Zend_Registry">
<link rel="chapter" href="zend.rest.html" title="Chapter 35. Zend_Rest">
<link rel="chapter" href="zend.search.lucene.html" title="Chapter 36. Zend_Search_Lucene">
<link rel="chapter" href="zend.server.html" title="Chapter 37. Zend_Server">
<link rel="chapter" href="zend.service.html" title="Chapter 38. Zend_Service">
<link rel="chapter" href="zend.session.html" title="Chapter 39. Zend_Session">
<link rel="chapter" href="zend.soap.html" title="Chapter 40. Zend_Soap">
<link rel="chapter" href="zend.test.html" title="Chapter 41. Zend_Test">
<link rel="chapter" href="zend.text.html" title="Chapter 42. Zend_Text">
<link rel="chapter" href="zend.timesync.html" title="Chapter 43. Zend_TimeSync">
<link rel="chapter" href="zend.translate.html" title="Chapter 44. Zend_Translate">
<link rel="chapter" href="zend.uri.html" title="Chapter 45. Zend_Uri">
<link rel="chapter" href="zend.validate.html" title="Chapter 46. Zend_Validate">
<link rel="chapter" href="zend.version.html" title="Chapter 47. Zend_Version">
<link rel="chapter" href="zend.view.html" title="Chapter 48. Zend_View">
<link rel="chapter" href="zend.xmlrpc.html" title="Chapter 49. Zend_XmlRpc">
<link rel="appendix" href="requirements.html" title="Appendix A. Zend Framework Requirements">
<link rel="appendix" href="coding-standard.html" title="Appendix B. Zend Framework Coding Standard for PHP">
<link rel="appendix" href="copyrights.html" title="Appendix C. Copyright Information">
<link rel="index" href="the.index.html" title="Index">
<link rel="section" href="zend.validate.html#zend.validate.introduction" title="46.1. Introduction">
<link rel="section" href="zend.validate.set.html" title="46.2. Standard Validation Classes">
<link rel="section" href="zend.validate.validator_chains.html" title="46.3. Validator Chains">
<link rel="section" href="zend.validate.writing_validators.html" title="46.4. Writing Validators">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader"><table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">Chapter 46. Zend_Validate</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="zend.uri.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="zend.validate.set.html">Next</a>
</td>
</tr>
</table></div>
<div class="chapter" lang="en">
<div class="titlepage"><div><div><h2 class="title">
<a name="zend.validate"></a>Chapter 46. Zend_Validate</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl>
<dt><span class="sect1"><a href="zend.validate.html#zend.validate.introduction">46.1. Introduction</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="zend.validate.html#zend.validate.introduction.definition">46.1.1. What is a validator?</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.html#zend.validate.introduction.using">46.1.2. Basic usage of validators</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.html#zend.validate.introduction.messages">46.1.3. Customizing messages</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.html#zend.validate.introduction.static">46.1.4. Using the static <code class="code">is()</code> method</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="zend.validate.set.html">46.2. Standard Validation Classes</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="zend.validate.set.html#zend.validate.set.alnum">46.2.1. Alnum</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.set.html#zend.validate.set.alpha">46.2.2. Alpha</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.set.html#zend.validate.set.barcode">46.2.3. Barcode</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.set.html#zend.validate.set.between">46.2.4. Between</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.set.html#zend.validate.set.ccnum">46.2.5. Ccnum</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.set.html#zend.validate.set.date">46.2.6. Date</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.set.html#zend.validate.set.digits">46.2.7. Digits</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.set.html#zend.validate.set.email_address">46.2.8. EmailAddress</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.set.html#zend.validate.set.float">46.2.9. Float</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.set.html#zend.validate.set.greater_than">46.2.10. GreaterThan</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.set.html#zend.validate.set.hex">46.2.11. Hex</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.set.html#zend.validate.set.hostname">46.2.12. Hostname</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.set.html#zend.validate.set.in_array">46.2.13. InArray</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.set.html#zend.validate.set.int">46.2.14. Int</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.set.html#zend.validate.set.ip">46.2.15. Ip</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.set.html#zend.validate.set.less_than">46.2.16. LessThan</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.set.html#zend.validate.set.not_empty">46.2.17. NotEmpty</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.set.html#zend.validate.set.regex">46.2.18. Regex</a></span></dt>
<dt><span class="sect2"><a href="zend.validate.set.html#zend.validate.set.string_length">46.2.19. StringLength</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="zend.validate.validator_chains.html">46.3. Validator Chains</a></span></dt>
<dt><span class="sect1"><a href="zend.validate.writing_validators.html">46.4. Writing Validators</a></span></dt>
</dl>
</div>
<div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="zend.validate.introduction"></a>46.1. Introduction</h2></div></div></div>
<p>
        The Zend_Validate component provides a set of commonly needed
        validators. It also provides a simple validator chaining mechanism by
        which multiple validators may be applied to a single datum in a
        user-defined order.
    </p>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.validate.introduction.definition"></a>46.1.1. What is a validator?</h3></div></div></div>
<p>
            A validator examines its input with respect to some requirements
            and produces a boolean result - whether the input successfully
            validates against the requirements. If the input does not meet the
            requirements, a validator may additionally provide information
            about which requirement(s) the input does not meet.
        </p>
<p>
            For example, a web application might require that a username be
            between six and twelve characters in length and may only contain
            alphanumeric characters. A validator can be used for ensuring that
            usernames meet these requirements. If a chosen username does not
            meet one or both of the requirements, it would be useful to know
            which of the requirements the username fails to meet.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.validate.introduction.using"></a>46.1.2. Basic usage of validators</h3></div></div></div>
<p>
            Having defined validation in this way provides the foundation for
            <code class="code">Zend_Validate_Interface</code>, which defines two methods,
            <code class="code">isValid()</code> and <code class="code">getMessages()</code>. The
            <code class="code">isValid()</code> method performs validation upon the provided
            value, returning <code class="code">true</code> if and only if the value passes
            against the validation criteria.
        </p>
<p>
            If <code class="code">isValid()</code> returns <code class="code">false</code>, the
            <code class="code">getMessages()</code> returns an array of messages explaining
            the reason(s) for validation failure. The array keys are short
            strings that identify the reasons for validation failure, and the
            array values are the corresponding human-readable string messages.
            The keys and values are class-dependent; each validation class
            defines its own set of validation failure messages and the unique
            keys that identify them. Each class also has a <code class="code">const</code>
            definition that matches each identifier for a validation failure
            cause.
        </p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
                The <code class="code">getMessages()</code> methods return validation
                failure information only for the most recent
                <code class="code">isValid()</code> call.  Each call to
                <code class="code">isValid()</code> clears any messages and errors caused by
                a previous <code class="code">isValid()</code> call, because it's likely
                that each call to <code class="code">isValid()</code> is made for a
                different input value.
            </p></td></tr>
</table></div>
<p>
            The following example illustrates validation of an e-mail address:

            </p>
<pre class="programlisting">&lt;?php
require_once 'Zend/Validate/EmailAddress.php';

$validator = new Zend_Validate_EmailAddress();

if ($validator-&gt;isValid($email)) {
    // email appears to be valid
} else {
    // email is invalid; print the reasons
    foreach ($validator-&gt;getMessages() as $messageId =&gt; $message) {
        echo "Validation failure '$messageId': $message\n";
    }
}
            </pre>
<p>

        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.validate.introduction.messages"></a>46.1.3. Customizing messages</h3></div></div></div>
<p>
            Validate classes provide a <code class="code">setMessage()</code> method with
            which you can specify the format of a message returned by
            <code class="code">getMessages()</code> in case of validation failure.  The
            first argument of this method is a string containing the error
            message.  You can include tokens in this string which will be
            substituted with data relevant to the validator.  The token
            <code class="code">%value%</code> is supported by all validators; this is
            substituted with the value you passed to <code class="code">isValid()</code>.
            Other tokens may be supported on a case-by-case basis in each
            validation class.  For example, <code class="code">%max%</code> is a token
            supported by <code class="code">Zend_Validate_LessThan</code>.
            The <code class="code">getMessageVariables()</code> method returns an array
            of variable tokens supported by the validator.
        </p>
<p>
            The second optional argument is a string that identifies the
            validation failure message template to be set, which is useful when
            a validation class defines more than one cause for failure. If you
            omit the second argument, <code class="code">setMessage()</code> assumes the
            message you specify should be used for the first message template
            declared in the validation class. Many validation classes only have
            one error message template defined, so there is no need to specify
            which message template you are changing.
        </p>
<p>
            </p>
<pre class="programlisting">&lt;?php
require_once 'Zend/Validate/StringLength.php';

$validator = new Zend_Validate_StringLength(8);

$validator-&gt;setMessage(
    'The string \'%value%\' is too short; it must be at least %min% characters',
    Zend_Validate_StringLength::TOO_SHORT);

if (!$validator-&gt;isValid('word')) {
    $messages = $validator-&gt;getMessages();
    echo current($messages);

    // echoes "The string 'word' is too short; it must be at least 8 characters"
}
            </pre>
<p>
        </p>
<p>
            You can set multiple messages using the <code class="code">setMessages()</code>
            method.  Its argument is an array containing key/message pairs.

            </p>
<pre class="programlisting">&lt;?php
require_once 'Zend/Validate/StringLength.php';

$validator = new Zend_Validate_StringLength(8, 12);

$validator-&gt;setMessages( array(
    Zend_Validate_StringLength::TOO_SHORT =&gt; 'The string \'%value%\' is too short',
    Zend_Validate_StringLength::TOO_LONG  =&gt; 'The string \'%value%\' is too long'
));
            </pre>
<p>

        </p>
<p>
            If your application requires even greater flexibility with which it
            reports validation failures, you can access properties by the same
            name as the message tokens supported by a given validation class.
            The <code class="code">value</code> property is always available in a validator;
            it is the value you specified as the argument of
            <code class="code">isValid()</code>.  Other properties may be supported on a
            case-by-case basis in each validation class.

            </p>
<pre class="programlisting">&lt;?php
require_once 'Zend/Validate/StringLength.php';

$validator = new Zend_Validate_StringLength(8, 12);

if (!validator-&gt;isValid('word')) {
    echo 'Word failed: '
        . $validator-&gt;value
        . '; its length is not between '
        . $validator-&gt;min
        . ' and '
        . $validator-&gt;max
        . "\n";
}
            </pre>
<p>
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.validate.introduction.static"></a>46.1.4. Using the static <code class="code">is()</code> method</h3></div></div></div>
<p>
            If it's inconvenient to load a given validation class and create an
            instance of the validator, you can use the static method
            <code class="code">Zend_Validate::is()</code> as an alternative invocation
            style.  The first argument of this method is a data input value,
            that you would pass to the <code class="code">isValid()</code> method.  The
            second argument is a string, which corresponds to the basename of
            the validation class, relative to the <code class="code">Zend_Validate</code>
            namespace.  The <code class="code">is()</code> method automatically loads the
            class, creates an instance, and applies the <code class="code">isValid()</code>
            method to the data input.

            </p>
<pre class="programlisting">&lt;?php
require_once 'Zend/Validate.php';

if (Zend_Validate::is($email, 'EmailAddress')) {
    // Yes, email appears to be valid
}
            </pre>
<p>

        </p>
<p>
            You can also pass an array of constructor arguments, if they
            are needed for the validator.

            </p>
<pre class="programlisting">&lt;?php
require_once 'Zend/Validate.php';

if (Zend_Validate::is($value, 'Between', array(1, 12))) {
    // Yes, $value is between 1 and 12
}
            </pre>
<p>

        </p>
<p>
            The <code class="code">is()</code> method returns a boolean value, the same as
            the <code class="code">isValid()</code> method.  When using the static
            <code class="code">is()</code> method, validation failure messages are not
            available.
        </p>
<p>
            The static usage can be convenient for invoking a validator ad hoc,
            but if you have the need to run a validator for multiple inputs,
            it's more efficient to use the non-static usage, creating an
            instance of the validator object and calling its
            <code class="code">isValid()</code> method.
        </p>
<p>
            Also, the <code class="code">Zend_Filter_Input</code> class allows you to
            instantiate and run multiple filter and validator classes on demand
            to process sets of input data. See
            <a href="zend.filter.input.html" title="16.5. Zend_Filter_Input">Section 16.5, “Zend_Filter_Input”</a>.
        </p>
</div>
</div>
</div>
<div class="navfooter"><table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="zend.uri.html">Prev</a> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href="zend.validate.set.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 45. Zend_Uri </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> 46.2. Standard Validation Classes</td>
</tr>
</table></div>
<div class="revinfo"></div>
</body>
</html>
